*-----------------------------------------------------------------------*
*		   Falcon MC68040 CPU ToolKit v5.00			* 
*-----------------------------------------------------------------------*

Introduction:

The MC68040 ToolKit is a selection of drivers, patches and tools designed
to get the very best out of the 68040 processor. It allows the CPU caches
and FastRAM to be used safely with software that normally would not be
able to work properly, and improves system performance significantly.

*-----------------------------------------------------------------------*

TKROMDRV.PRG description:

Please read this properly before using!

This is the main ToolKit driver. It installs itself as a reset-resident
patch, so that any changes made to the ROM remain semi-permanent until
the next cold boot or power-off. The other ToolKit utilities will not
function without this program installed. Configuration of this program
is achieved via an external configuration tool. See documentation on
this tool for more specific details.

The TKROMDRV.PRG driver is responsible for the following enhancements:

FastRAM features:

* Locates all FastRAM memory plugged into the available SIMM banks.
* Joins the memory chunks to create a single contiguous memory pool.
* Announces new memory pool to the OS, for use by normal applications.
* Installs '_FRB' FastRAM buffer + cookie to allow safe disk DMA.
* FastRAM buffer made non-cacheable, allowing cache-friendly disk DMA.
* Option to search both SIMM banks, or search only the first bank.
* Optional supervisor stack space converted to FastRAM pages for speed.

CPU Cache features:

* Installs a CPU cache handler to maintain user cache configuration.
* Enables CPU instruction and/or data caches in the auto folder.
* Optional supervisor stack space converted to copyback cache mode.
* Reset-resident feature enables instruction cache from a warm reset.
* Optional patch temporarily disables instruction cache on 'Pexec'.
* Option to select cacheable/noncacheable FastRAM.
* Option to select cacheable/noncacheable ROM.
* Option to select cacheable/noncacheable video on Videl and Nova.

Miscellaneous features.

* Nemesis 40MHz option from a warm reset.
* GEMRAM emulation in FastRAM for WINX users.
* Optional write-protected ROM space.
* Optional FastRAM memory check.
* Alternative boot-logo from a warm reset (scorpion).

*-----------------------------------------------------------------------*

DMASNOOP.PRG description: 

Please read this properly before using!

DMASNOOP.PRG is a small utility which runs from the auto folder and
converts all remaining ST-RAM into non-cacheable memory. This program is
not really needed for most setups, but certain applications will rely
on this for safe SCSI disk access and/or faultless audio record/playback.

The Falcon has no 'bus-snooping' capability when a 68040 is present, at
least in the form of Afterburner040. This means that data transferred via
DMA hardware will not be noticed by the processor's caches - and so major
differences can arise between the actual contents of RAM and the expected
contents of the CPU - the data cache in particular. DMA devices include
things like SCSI, Floppy disk, Blitter (this is now off-limits anyway),
Audio hardware and certain (rare) DSP operations. The only way to make
these functions 100% safe with some software is to make sure ST-RAM used
by those applications can never be cached by the CPU - after all, stale
data can never occur in the cache if the cache never holds the data in
the first place! DMASNOOP simply prevents ST-RAM from being cached by the
CPU and so compatibility with direct-DMA supporting software increases.

It is important to note that DMASNOOP only converts REMAINING ST-RAM
to non-cacheable memory. ST-RAM used by programs executed before
DMASNOOP in the auto folder is *not* affected, and remains cacheable.

Any software actually running in ST-RAM with DMASNOOP installed will
unfortunately run _very_ slowly because the caches will act like they
are disabled, so it is important to run everything from FastRAM where
possible. Even programs relying on DMA should be able to run from
FastRAM so long as they allocate buffers and resources from ST-RAM. This
can be achieved by setting the TT-Prg flag and clearing the TT-Malloc
flag in the program header. If this doesn't work, and you can't stand
the slow speed of programs relying entirely on ST-RAM, you will have
to risk running without DMASNOOP and just hope that the software does
not suffer from stale cache data.

A good compromise in these cases is running without DMASNOOP, but
with the data cache turned off. It is usually the data cache which
causes such problems, and it has the least impact on program execution
so turning it off is a good alternative to using DMASNOOP when FastRAM
is just not an option.

Since most software never relies on direct DMA, you can normally run
happily without DMASNOOP, and with both caches enabled. If you don't
have SCSI devices fitted, your need for DMASNOOP is greatly reduced.


So, to re-iterate (and compress) what has been covered above...

DMASNOOP is needed *only* when programs are likely to use ST-RAM for
direct-DMA transfers, which normally means SCSI, Floppy or Audio.

Since the harddisk driver and OS are already capable of dealing with
direct DMA, these don't count. It's only when *additional* software
is likely to 'detour' around the OS that things get a little risky.

This 'additional' software includes things like 3rd party disk caches,
low-level disk copiers, sound samplers, disk formatters etc. etc.

Some examples of software with known DMA/cache problems include:

* TCACHE63 	Requires DMASNOOP when told to malloc from ST-RAM,
		although this is not necessary if told to malloc
		from FastRAM. Some people (14MB users) may want to
		spend large wads of ST-RAM on a disk cache, since
		it's not much needed for anything else. This is a
		good reason for installing DMASNOOP.

(list still being updated)

*-----------------------------------------------------------------------*

TKBUBBLE.PRG description:

Please read this properly before using!

This program is not actually necessary, but it can help in certain
cases where nasty 68030-only software disables the CPU caches and the
ToolKit driver is expected to notice this and re-enable them again.

The ToolKit frequently makes sure the CPU caches reflect the user's
desired configuration. Some programs fiddle with the caches, and can
accidentally turn them off (not expecting to see a 68040 installed!).
Normally, the ToolKit will very quickly see what has taken place and
re-initialise the caches with the appropriate flushing operations.

When lots of drivers and patches are installed, the ToolKit patches can
get pushed to the bottom of the pile, and the code which monitors the
CPU caches ends up being executed far less frequently - possibly even
never! NVDI is known to replace lots of OS calls, and tends to get in
the way of the TK cache controller. By installing TKBUBBLE in the auto
folder, you can 'move' the TK cache controller to some point later in
the auto folder than the offending software - NVDI in this case. That
is why TKBUBBLE is best executed right after NVDI.

If you find your machine sometimes slows down for no well explained
reason, even if the utilities claim the caches are enabled, they could
well be turned off, and just haven't been updated because NVDI is getting
in the way. TKBUBBLE.PRG is the solution.

*-----------------------------------------------------------------------*

Installation:

It is important to read all of the documentation before attempting to use
this software. Having done this, you can install the drivers very easily
by placing them in your auto folder as follows:

The flags shown as F.P.M refer to (F)astload / TT-(P)rg / TT-(M)alloc.

The values for the flags are 'y' (yes), 'n' (no) and 'x' (don't care).

Program		F.P.M
---------------------
TKROMDRV.PRG	y y y	(this must always come first)
MAGXBOOT.PRG	y y y	(if applicable)
DMASNOOP.PRG    y n x	(optional - helps with HD caches & audio stuff)
68882DRV.PRG    y y y	(you need this for FPU-based software)

HDDRIVER.PRG	y y y	(if applicable)
BCACHE40.PRG	y y x	(enables dcache _only_ after HDDriver logs SCSI!)

............    .....	(various drivers etc.)

NVDI.PRG	y y y
TKBUBBLE.PRG	y y y	(stops NVDI getting in the way of TK patch)

............    .....	(various drivers etc.)

TCACHE63.PRG	y y y	(cache pool kept in FastRAM - this works fine)
(..or..)
TCACHE63.PRG	y y n	(cache pool kept in ST-RAM - requires DMASNOOP!)

The order and flag settings for the programs described are only typical
examples, and may not apply to your system. The most important part
of the boot sequence is the very earliest part - particularly when Magic
and/or HDDriver are being used. Getting the order or flags wrong could
lead to nasty problems. More detail on this will be given later in the 
documentation if you are in doubt about the auto folder installation.

*-----------------------------------------------------------------------*
 
Miscellaneous known problems:

Problems can arise with the harddisk driver when the copyback/fastram
options are used on the supervisor stack space. The solution is either
to disable these options, or to run a second copy of the harddisk driver
in the auto folder, where the software will be kept clear of the modified
supervisor stack memory. The zone where the harddisk driver loads at
boot time is very close to the affected stack memory, and this is why
there can be occasional conflicts.

Sometimes it can help to re-run the harddisk driver in the auto folder
anyway, since some drivers (like HDDriver 6.3x) can run from FastRAM!

*-----------------------------------------------------------------------*
